home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / string.n < prev    next >
Encoding:
Text File  |  1995-02-22  |  5.1 KB  |  133 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) string.n 1.4 95/02/22 14:37:26
  9. '\" 
  10. .so man.macros
  11. .HS string tcl 7.4
  12. .BS
  13. '\" Note:  do not modify the .SH NAME line immediately below!
  14. .SH NAME
  15. string \- Manipulate strings
  16. .SH SYNOPSIS
  17. \fBstring \fIoption arg \fR?\fIarg ...?\fR
  18. .BE
  19.  
  20. .SH DESCRIPTION
  21. .PP
  22. Performs one of several string operations, depending on \fIoption\fR.
  23. The legal \fIoption\fRs (which may be abbreviated) are:
  24. .TP
  25. \fBstring compare \fIstring1 string2\fR
  26. Perform a character-by-character comparison of strings \fIstring1\fR and
  27. \fIstring2\fR in the same way as the C \fBstrcmp\fR procedure.  Return
  28. \-1, 0, or 1, depending on whether \fIstring1\fR is lexicographically
  29. less than, equal to, or greater than \fIstring2\fR.
  30. .TP
  31. \fBstring first \fIstring1 string2\fR
  32. Search \fIstring2\fR for a sequence of characters that exactly match
  33. the characters in \fIstring1\fR.  If found, return the index of the
  34. first character in the first such match within \fIstring2\fR.  If not
  35. found, return \-1.
  36. .TP
  37. \fBstring index \fIstring charIndex\fR
  38. Returns the \fIcharIndex\fR'th character of the \fIstring\fR
  39. argument.  A \fIcharIndex\fR of 0 corresponds to the first
  40. character of the string.
  41. If \fIcharIndex\fR is less than 0 or greater than
  42. or equal to the length of the string then an empty string is
  43. returned.
  44. .TP
  45. \fBstring last \fIstring1 string2\fR
  46. Search \fIstring2\fR for a sequence of characters that exactly match
  47. the characters in \fIstring1\fR.  If found, return the index of the
  48. first character in the last such match within \fIstring2\fR.  If there
  49. is no match, then return \-1.
  50. .TP
  51. \fBstring length \fIstring\fR
  52. Returns a decimal string giving the number of characters in \fIstring\fR.
  53. .TP
  54. \fBstring match \fIpattern\fR \fIstring\fR
  55. See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0
  56. if it doesn't.  Matching is done in a fashion similar to that
  57. used by the C-shell.  For the two strings to match, their contents
  58. must be identical except that the following special sequences
  59. may appear in \fIpattern\fR:
  60. .RS
  61. .IP \fB*\fR 10
  62. Matches any sequence of characters in \fIstring\fR,
  63. including a null string.
  64. .IP \fB?\fR 10
  65. Matches any single character in \fIstring\fR.
  66. .IP \fB[\fIchars\fB]\fR 10
  67. Matches any character in the set given by \fIchars\fR.  If a sequence
  68. of the form
  69. \fIx\fB\-\fIy\fR appears in \fIchars\fR, then any character
  70. between \fIx\fR and \fIy\fR, inclusive, will match.
  71. .IP \fB\e\fIx\fR 10
  72. Matches the single character \fIx\fR.  This provides a way of
  73. avoiding the special interpretation of the characters
  74. \fB*?[]\e\fR in \fIpattern\fR.
  75. .RE
  76. .TP
  77. \fBstring range \fIstring first last\fR
  78. Returns a range of consecutive characters from \fIstring\fR, starting
  79. with the character whose index is \fIfirst\fR and ending with the
  80. character whose index is \fIlast\fR.  An index of 0 refers to the
  81. first character of the string.  \fILast\fR may be \fBend\fR (or any
  82. abbreviation of it) to refer to the last character of the string.
  83. If \fIfirst\fR is less than zero then it is treated as if it were zero, and
  84. if \fIlast\fR is greater than or equal to the length of the string then
  85. it is treated as if it were \fBend\fR.  If \fIfirst\fR is greater than
  86. \fIlast\fR then an empty string is returned.
  87. .TP
  88. \fBstring tolower \fIstring\fR
  89. Returns a value equal to \fIstring\fR except that all upper case
  90. letters have been converted to lower case.
  91. .TP
  92. \fBstring toupper \fIstring\fR
  93. Returns a value equal to \fIstring\fR except that all lower case
  94. letters have been converted to upper case.
  95. .TP
  96. \fBstring trim \fIstring\fR ?\fIchars\fR?
  97. Returns a value equal to \fIstring\fR except that any leading
  98. or trailing characters from the set given by \fIchars\fR are
  99. removed.
  100. If \fIchars\fR is not specified then white space is removed
  101. (spaces, tabs, newlines, and carriage returns).
  102. .TP
  103. \fBstring trimleft \fIstring\fR ?\fIchars\fR?
  104. Returns a value equal to \fIstring\fR except that any
  105. leading characters from the set given by \fIchars\fR are
  106. removed.
  107. If \fIchars\fR is not specified then white space is removed
  108. (spaces, tabs, newlines, and carriage returns).
  109. .TP
  110. \fBstring trimright \fIstring\fR ?\fIchars\fR?
  111. Returns a value equal to \fIstring\fR except that any
  112. trailing characters from the set given by \fIchars\fR are
  113. removed.
  114. If \fIchars\fR is not specified then white space is removed
  115. (spaces, tabs, newlines, and carriage returns).
  116. .TP
  117. \fBstring wordend \fIstring index\fR
  118. .VS
  119. Returns the index of the character just after the last one in the
  120. word containing character \fIindex\fR of \fIstring\fR.
  121. A word is considered to be any contiguous range of alphanumeric
  122. or underscore characters, or any single character other than these.
  123. .TP
  124. \fBstring wordstart \fIstring index\fR
  125. Returns the index of the first character in the
  126. word containing character \fIindex\fR of \fIstring\fR.
  127. A word is considered to be any contiguous range of alphanumeric
  128. or underscore characters, or any single character other than these.
  129. .VE
  130.  
  131. .SH KEYWORDS
  132. case conversion, compare, index, match, pattern, string, word
  133.